<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Net::LibAsyncNS - a Perl wrapper around libasyncns - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of Net-LibAsyncNS - MetaCPAN" href="https://metacpan.org/dist/Net-LibAsyncNS/releases.rss" />
        <link rel="canonical" href="./Net::LibAsyncNS.html" />
        <meta name="description" content="a Perl wrapper around libasyncns" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/Net::LibAsyncNS" />
<meta name="twitter:title"       content="Net::LibAsyncNS" />
<meta name="twitter:description" content="a Perl wrapper around libasyncns" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./Net::LibAsyncNS.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of Net-LibAsyncNS was released.">
      <span class="relatize">21 Nov 2020 13:25:50 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/Net-LibAsyncNS">Net-LibAsyncNS</a>
  </li>
  <li>
    Module version: 0.04
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/Net-LibAsyncNS/source/lib/Net/LibAsyncNS.pm">Source</a>
    (<a href="https://metacpan.org/dist/Net-LibAsyncNS/source/lib/Net/LibAsyncNS.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/Net-LibAsyncNS/source/lib/Net">Browse</a>
    (<a href="https://metacpan.org/dist/Net-LibAsyncNS/source/lib/Net?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/Net-LibAsyncNS/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/Net-LibAsyncNS/contribute">How to Contribute</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=Net-LibAsyncNS">Issues</a>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=Net-LibAsyncNS+0.04" title="Matrix">Testers</a>
        <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/N/Net-LibAsyncNS.html?oncpan=1&amp;distmat=1&amp;version=0.04&amp;grade=2" style="color: #090">94</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/N/Net-LibAsyncNS.html?oncpan=1&amp;distmat=1&amp;version=0.04&amp;grade=3" style="color: #900">0</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/N/Net-LibAsyncNS.html?oncpan=1&amp;distmat=1&amp;version=0.04&amp;grade=4">0</a>)</span>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/PEVANS/Net-LibAsyncNS-0.04">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on Net-LibAsyncNS who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 1
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/Net-LibAsyncNS-0.04/index.html">% Coverage </a>
    </li>
    <li>
      License: perl_5
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/Net-LibAsyncNS/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/P/PE/PEVANS/Net-LibAsyncNS-0.04.tar.gz">
      Download (<span itemprop="fileSize">22.1KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FPEVANS%2FNet-LibAsyncNS-0.04%2Flib%2FNet%2FLibAsyncNS.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Net-LibAsyncNS/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Net-LibAsyncNS/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:Net-LibAsyncNS">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="Net-LibAsyncNS">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Net/LibAsyncNS.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="PEVANS/Net-LibAsyncNS-0.04"
>0.04
  (PEVANS on 2020-11-21)</option>
<option
  
  value="PEVANS/Net-LibAsyncNS-0.02"
>0.02
  (PEVANS on 2014-03-28)</option>
<option
  
  value="PEVANS/Net-LibAsyncNS-0.01"
>0.01
  (PEVANS on 2010-11-06)</option>
<optgroup label="BackPAN">'
<option
  
  value="PEVANS/Net-LibAsyncNS-0.03"
>0.03
  (PEVANS on 2020-11-04)</option>
</optgroup>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/PEVANS/Net-LibAsyncNS-0.04/diff/' + encodeURIComponent(this.value) + '/lib/Net/LibAsyncNS.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="PEVANS/Net-LibAsyncNS-0.04"
>0.04
  (PEVANS on 2020-11-21)</option>
<option
  
  value="PEVANS/Net-LibAsyncNS-0.02"
>0.02
  (PEVANS on 2014-03-28)</option>
<option
  
  value="PEVANS/Net-LibAsyncNS-0.01"
>0.01
  (PEVANS on 2010-11-06)</option>
<optgroup label="BackPAN">'
<option
  
  value="PEVANS/Net-LibAsyncNS-0.03"
>0.03
  (PEVANS on 2020-11-04)</option>
</optgroup>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><a href="https://metacpan.org/pod/Exporter" title="Exporter" class="ellipsis">Exporter</a></li>
  <li><i class="ttip" title="dynamic_config enabled">and possibly others</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/Net::LibAsyncNS/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=Net%3A%3ALibAsyncNS">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=Net-LibAsyncNS">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/PEVANS/Net-LibAsyncNS-0.04/view/lib/Net/LibAsyncNS.pm">This version</a>
    </li>
    <li>
      <a href="./Net::LibAsyncNS.html">Latest version</a>
    </li>
    <li>
    </li>
    <li>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/PEVANS" class="author-name">Paul Evans</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Net/LibAsyncNS.pm&#39;" class="">
<option
  selected
  value="PEVANS/Net-LibAsyncNS-0.04"
>0.04
  (PEVANS on 2020-11-21)</option>
<option
  
  value="PEVANS/Net-LibAsyncNS-0.02"
>0.02
  (PEVANS on 2014-03-28)</option>
<option
  
  value="PEVANS/Net-LibAsyncNS-0.01"
>0.01
  (PEVANS on 2010-11-06)</option>
<optgroup label="BackPAN">'
<option
  
  value="PEVANS/Net-LibAsyncNS-0.03"
>0.03
  (PEVANS on 2020-11-04)</option>
</optgroup>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/Net-LibAsyncNS">Net-LibAsyncNS-0.04</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage one &#10;
          • 1 direct dependent &#10;          • 1 total dependent
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="5"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="10"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="Net-LibAsyncNS-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="Net-LibAsyncNS-0.04">
    <input type="hidden" name="author" value="PEVANS">
    <input type="hidden" name="distribution" value="Net-LibAsyncNS">
    <button type="submit" class="favorite"><span></span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./Net::LibAsyncNS.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite">
<span></span> ++</a>
</div>
   / <span>Net::LibAsyncNS</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./Net::LibAsyncNS.html#NAME">NAME</a></li>
  <li><a href="./Net::LibAsyncNS.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./Net::LibAsyncNS.html#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="./Net::LibAsyncNS.html#CONSTRUCTOR">CONSTRUCTOR</a>
    <ul>
      <li><a href="./Net::LibAsyncNS.html#new">new</a></li>
    </ul>
  </li>
  <li><a href="./Net::LibAsyncNS.html#METHODS">METHODS</a>
    <ul>
      <li><a href="./Net::LibAsyncNS.html#fd">fd</a></li>
      <li><a href="./Net::LibAsyncNS.html#new_handle_for_fd">new_handle_for_fd</a></li>
      <li><a href="./Net::LibAsyncNS.html#wait">wait</a></li>
      <li><a href="./Net::LibAsyncNS.html#getnqueries">getnqueries</a></li>
      <li><a href="./Net::LibAsyncNS.html#getaddrinfo">getaddrinfo</a></li>
      <li><a href="./Net::LibAsyncNS.html#getaddrinfo_done">getaddrinfo_done</a></li>
      <li><a href="./Net::LibAsyncNS.html#getnameinfo">getnameinfo</a></li>
      <li><a href="./Net::LibAsyncNS.html#getnameinfo_done">getnameinfo_done</a></li>
      <li><a href="./Net::LibAsyncNS.html#res_query">res_query</a></li>
      <li><a href="./Net::LibAsyncNS.html#res_search">res_search</a></li>
      <li><a href="./Net::LibAsyncNS.html#res_done">res_done</a></li>
      <li><a href="./Net::LibAsyncNS.html#isdone">isdone</a></li>
      <li><a href="./Net::LibAsyncNS.html#getnext">getnext</a></li>
      <li><a href="./Net::LibAsyncNS.html#cancel">cancel</a></li>
      <li><a href="./Net::LibAsyncNS.html#setuserdata">setuserdata</a></li>
      <li><a href="./Net::LibAsyncNS.html#getuserdata">getuserdata</a></li>
    </ul>
  </li>
  <li><a href="./Net::LibAsyncNS.html#CONSTANTS">CONSTANTS</a></li>
  <li><a href="./Net::LibAsyncNS.html#QUERY-OBJECTS">QUERY OBJECTS</a>
    <ul>
      <li><a href="./Net::LibAsyncNS.html#asyncns">asyncns</a></li>
      <li><a href="./Net::LibAsyncNS.html#isdone1">isdone</a></li>
      <li><a href="./Net::LibAsyncNS.html#setuserdata1">setuserdata</a></li>
      <li><a href="./Net::LibAsyncNS.html#getuserdata1">getuserdata</a></li>
    </ul>
  </li>
  <li><a href="./Net::LibAsyncNS.html#EXAMPLES">EXAMPLES</a>
    <ul>
      <li><a href="./Net::LibAsyncNS.html#Multiple-Queries">Multiple Queries</a></li>
      <li><a href="./Net::LibAsyncNS.html#Non-blocking-IO">Non-blocking IO</a></li>
    </ul>
  </li>
  <li><a href="./Net::LibAsyncNS.html#SEE-ALSO">SEE ALSO</a></li>
  <li><a href="./Net::LibAsyncNS.html#AUTHOR">AUTHOR</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p><code>Net::LibAsyncNS</code> - a Perl wrapper around <i>libasyncns</i></p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code>   use Net::LibAsyncNS;
   use Socket qw( SOCK_RAW );

   my $asyncns = Net::LibAsyncNS-&gt;new( 1 );

   # By specifying this socktype hint, we only get one result per address family
   my %hints = ( socktype =&gt; SOCK_RAW );

   my $query = $asyncns-&gt;getaddrinfo( &quot;localhost&quot;, undef, \%hints );

   while( $asyncns-&gt;getnqueries ) {
      $asyncns-&gt;wait( 1 );

      if( $query-&gt;isdone ) {
         my ( $err, @res ) = $asyncns-&gt;getaddrinfo_done( $query );
         die &quot;getaddrinfo - $err&quot; if $err;

         foreach my $res ( @res ) {
            printf &quot;family=%d, addr=%v02x\n&quot;, $res-&gt;{family}, $res-&gt;{addr};
         }
      }
   }</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>The name resolver functions <code>getaddrinfo</code> and <code>getnameinfo</code> as provided by most C libraries are blocking functions; they will perform their work and return an answer when it is ready. This makes it hard to use these name resolvers in asynchronous or non-blocking code.</p>

<p>The <i>libasyncns</i> library provides a way to invoke these library functions from within an asynchronous or non-blocking program. Individual resolver queries are made by calling a function which returns an object representing an outstanding query (a kind of future). A filehandle is provided by the resolver to watch for readability; when it is readable, a function should be called to collect completed queries. The example in the SYNOPSIS above does not demonstrate this; see the EXAMPLES section below for one that does.</p>

<h1 id="CONSTRUCTOR">CONSTRUCTOR</h1>

<h2 id="new">new</h2>

<pre><code>   $asyncns = Net::LibAsyncNS-&gt;new( $n_proc )</code></pre>

<p>Construct a new <code>Net::LibAsyncNS</code> object. It will be initialised with <code>$n_proc</code> processes or threads to handle nameserver lookups.</p>

<h1 id="METHODS">METHODS</h1>

<h2 id="fd">fd</h2>

<pre><code>   $fd = $asyncns-&gt;fd</code></pre>

<p>Returns a file descriptor number to poll for readability on.</p>

<h2 id="new_handle_for_fd">new_handle_for_fd</h2>

<pre><code>   $handle = $asyncns-&gt;new_handle_for_fd</code></pre>

<p>Returns a new <code>IO::Handle</code> object wrapping the underlying file descriptor. Note that the handle is <i>not</i> cached; a new object is created each time this method is called. For well-behaved results, this should only be called once.</p>

<h2 id="wait">wait</h2>

<pre><code>   $success = $asyncns-&gt;wait( $block )</code></pre>

<p>Wait for more queries to be ready. If <code>$block</code> is true, this method will block until at least one query is ready, if false it will process any pending IO without blocking. It returns true if the operation was successful or false if an IO error happened; <code>$!</code> will be set in this case.</p>

<h2 id="getnqueries">getnqueries</h2>

<pre><code>   $n = $asyncns-&gt;getnqueries</code></pre>

<p>Return the number of outstanding queries.</p>

<h2 id="getaddrinfo">getaddrinfo</h2>

<pre><code>   $q = $asyncns-&gt;getaddrinfo( $host, $service, $hints )</code></pre>

<p>Starts an asynchronous <code>getaddrinfo</code> resolution on the given <code>$host</code> and <code>$service</code> names. If provided, <code>$hints</code> should be a HASH reference where the following keys are recognised:</p>

<dl>

<dt id="flags-=&gt;-INT"><a id="flags"></a><a id="flags---INT"></a>flags =&gt; INT</dt>
<dd>

</dd>
<dt id="family-=&gt;-INT"><a id="family"></a><a id="family---INT"></a>family =&gt; INT</dt>
<dd>

</dd>
<dt id="socktype-=&gt;-INT"><a id="socktype"></a><a id="socktype---INT"></a>socktype =&gt; INT</dt>
<dd>

</dd>
<dt id="protocol-=&gt;-INT"><a id="protocol"></a><a id="protocol---INT"></a>protocol =&gt; INT</dt>
<dd>

</dd>
</dl>

<h2 id="getaddrinfo_done">getaddrinfo_done</h2>

<pre><code>   ( $err, @res ) = $asyncns-&gt;getaddrinfo_done( $q )</code></pre>

<p>Finishes a <code>getaddrinfo</code> resolution, returning an error code, and a list of results. Each result will be a HASH reference containing the following keys:</p>

<dl>

<dt id="family-=&gt;-INT1"><a id="family1"></a><a id="family---INT1"></a>family =&gt; INT</dt>
<dd>

</dd>
<dt id="socktype-=&gt;-INT1"><a id="socktype1"></a><a id="socktype---INT1"></a>socktype =&gt; INT</dt>
<dd>

</dd>
<dt id="protocol-=&gt;-INT1"><a id="protocol1"></a><a id="protocol---INT1"></a>protocol =&gt; INT</dt>
<dd>

<p>Socket type values to pass to <code>socket</code></p>

</dd>
<dt id="addr-=&gt;-STRING"><a id="addr"></a><a id="addr---STRING"></a>addr =&gt; STRING</dt>
<dd>

<p>Address to pass to <code>connect</code></p>

</dd>
<dt id="canonname-=&gt;-STRING"><a id="canonname"></a><a id="canonname---STRING"></a>canonname =&gt; STRING</dt>
<dd>

<p>If requested, the canonical hostname for this address</p>

</dd>
</dl>

<h2 id="getnameinfo">getnameinfo</h2>

<pre><code>   $q = $asyncns-&gt;getnameinfo( $addr, $flags, $wanthost, $wantserv )</code></pre>

<p>Starts an asynchronous <code>getnameinfo</code> resolution on the given address. The <code>$wanthost</code> and <code>$wantserv</code> booleans indicate if the hostname or service name are required.</p>

<h2 id="getnameinfo_done">getnameinfo_done</h2>

<pre><code>   ( $err, $host, $service ) = $asyncns-&gt;getnameinfo_done( $q )</code></pre>

<p>Finishes a <code>getnameinfo</code> resolution, returning an error code, the hostname and service name, if requested.</p>

<h2 id="res_query">res_query</h2>

<h2 id="res_search">res_search</h2>

<pre><code>   $q = $asyncns-&gt;res_query( $dname, $class, $type )

   $q = $asyncns-&gt;res_search( $dname, $class, $type )</code></pre>

<p>Starts an asynchronous <code>res_query</code> or <code>res_search</code> resolution on the given domain name, class and type.</p>

<h2 id="res_done">res_done</h2>

<pre><code>   $answer = $asyncns-&gt;res_done( $q )</code></pre>

<p>Finishes a <code>res_query</code> or <code>res_search</code> resolution, returning the answer in a packed string, or <code>undef</code> if it fails. If it fails <code>$!</code> will contain the error details.</p>

<h2 id="isdone">isdone</h2>

<pre><code>   $done = $asyncns-&gt;isdone( $q )</code></pre>

<p>Returns true if the given query is ready.</p>

<h2 id="getnext">getnext</h2>

<pre><code>   $q = $asyncns-&gt;getnext</code></pre>

<p>Returns the next query object that is completed, or <code>undef</code> if none are ready yet. This will only yet be valid after calling the <code>wait</code> method at least once.</p>

<h2 id="cancel">cancel</h2>

<pre><code>   $asyncns-&gt;cancel( $q )</code></pre>

<p>Cancels a currently outstanding query. After this is called, the query in <code>$q</code> should not be further accessed, as memory associated with it will have been reclaimed.</p>

<h2 id="setuserdata">setuserdata</h2>

<pre><code>   $asyncns-&gt;setuserdata( $q, $data )</code></pre>

<p>Stores an arbitrary Perl scalar with the query. It can later be retrieved using <code>getuserdata</code>.</p>

<h2 id="getuserdata">getuserdata</h2>

<pre><code>   $data = $asyncns-&gt;getuserdata( $q )</code></pre>

<p>Returns the Perl scalar previously stored with the query, or <code>undef</code> if no value has yet been set.</p>

<h1 id="CONSTANTS">CONSTANTS</h1>

<p>The following constants are provided by <a href="https://metacpan.org/pod/Net::LibAsyncNS::Constants">Net::LibAsyncNS::Constants</a>.</p>

<p>Flags for <code>getaddrinfo</code>:</p>

<pre><code>   AI_PASSIVE
   AI_CANONNAME
   AI_NUMERICHOST
   AI_NUMERICSERV</code></pre>

<p>Error values:</p>

<pre><code>   EAI_BADFLAGS
   EAI_NONAME
   EAI_AGAIN
   EAI_FAIL
   EAI_NODATA
   EAI_FAMILY
   EAI_SERVICE
   EAI_SOCKTYPE
   EAI_ADDRFAMILY
   EAI_MEMORY</code></pre>

<p>Flags for <code>getnameinfo</code>:</p>

<pre><code>   NI_NUMERICHOST
   NI_NUMERICSERV
   NI_NAMEREQD
   NI_DGRAM</code></pre>

<h1 id="QUERY-OBJECTS"><a id="QUERY"></a>QUERY OBJECTS</h1>

<p>The following methods are available on query objects, returned by <code>getaddrinfo</code> and <code>getnameinfo</code>.</p>

<h2 id="asyncns">asyncns</h2>

<pre><code>   $asyncns = $query-&gt;asyncns</code></pre>

<p>Returns the underlying <code>Net::LibAsyncNS</code> object backing the query</p>

<h2 id="isdone1">isdone</h2>

<pre><code>   $done = $query-&gt;isdone</code></pre>

<h2 id="setuserdata1">setuserdata</h2>

<pre><code>   $query-&gt;setuserdata( $data )</code></pre>

<h2 id="getuserdata1">getuserdata</h2>

<pre><code>   $data = $query-&gt;getuserdata</code></pre>

<p>Shortcuts to the equivalent method on the underlying <code>Net::LibAsyncNS</code> object</p>

<h1 id="EXAMPLES">EXAMPLES</h1>

<h2 id="Multiple-Queries"><a id="Multiple"></a>Multiple Queries</h2>

<p>The SYNOPSIS example only has one outstanding query. To wait for multiple queries to complete, the <code>getnext</code> method can be used. Per-query context data can be stored in the query itself by using the <code>setuserdata</code> and <code>getuserdata</code> accessors.</p>

<pre><code>   use Net::LibAsyncNS;
   use Socket qw( SOCK_RAW );

   my $asyncns = Net::LibAsyncNS-&gt;new( 1 );

   my %hints = ( socktype =&gt; SOCK_RAW );
   my @hosts = qw( some hostnames here );

   foreach my $host ( @hosts ) {
      my $query = $asyncns-&gt;getaddrinfo( $host, undef, \%hints );
      $query-&gt;setuserdata( $host );
   }

   while( $asyncns-&gt;getnqueries ) {
      $asyncns-&gt;wait( 1 ) or die &quot;asyncns_wait: $!&quot;;

      while( my $query = $asyncns-&gt;getnext ) {
         my ( $err, @res ) = $asyncns-&gt;getaddrinfo_done( $query );
         my $host = $query-&gt;getuserdata;

         print &quot;$host - $err\n&quot; and next if $err;

         foreach my $res ( @res ) {
            printf &quot;%s is: family=%d, addr=%v02x\n&quot;, 
               $host, $res-&gt;{family}, $res-&gt;{addr};
         }
      }
   }</code></pre>

<p>In this example, the per-query data stored by <code>setuserdata</code> is just the hostname, but any Perl scalar may be stored, such as a HASH ref containing many keys, or CODE ref to a callback function of some kind.</p>

<h2 id="Non-blocking-IO"><a id="Non"></a>Non-blocking IO</h2>

<p>The examples above wait synchronously for the query/queries to complete, in the <code>wait</code> method. However, most of the point of this library is to allow asynchronous resolver calls to mix with other asynchronous and non-blocking code. This is achieved by the containing program waiting for a filehandle to become readable, and to call <code>$asyncns-&gt;wait( 0 )</code> when it is.</p>

<p>The following example shows integration with a simple <code>IO::Poll</code>-based program.</p>

<pre><code>   use IO::Poll;
   use Net::LibAsyncNS;
   use Socket qw( SOCK_RAW );

   my $asyncns = Net::LibAsyncNS-&gt;new( 1 );
   my %hints = ( socktype =&gt; SOCK_RAW );

   my @hosts = qw( some hostnames here );

   foreach my $host ( @hosts ) {
      my $query = $asyncns-&gt;getaddrinfo( $host, undef, \%hints );
      $query-&gt;setuserdata( $host );
   }

   my $asyncns_handle = $asyncns-&gt;new_handle_for_fd;

   my $poll = IO::Poll-&gt;new;
   $poll-&gt;mask( $asyncns_handle =&gt; POLLIN );

   while( $asyncns-&gt;getnqueries ) {
      defined $poll-&gt;poll or die &quot;poll() - $!&quot;;

      if( $poll-&gt;events( $asyncns_handle ) ) {
         while( my $query = $asyncns-&gt;getnext ) {
            my ( $err, @res ) = $asyncns-&gt;getaddrinfo_done( $query );
            my $host = $query-&gt;getuserdata;

            print &quot;$host - $err\n&quot; and next if $err;

            foreach my $res ( @res ) {
               printf &quot;%s is: family=%d, addr=%v02x\n&quot;, 
                  $host, $res-&gt;{family}, $res-&gt;{addr};
            }
         }
      }
   }</code></pre>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<ul>

<li><p><a href="http://0pointer.de/lennart/projects/libasyncns">http://0pointer.de/lennart/projects/libasyncns</a> is a C library for Linux/Unix for executing name service queries asynchronously. It is an asynchronous wrapper around getaddrinfo(3), getnameinfo(3), res_query(3) and res_search(3) from libc and libresolv.</p>

</li>
</ul>

<h1 id="AUTHOR">AUTHOR</h1>

<p>Paul Evans &lt;leonerd@leonerd.org.uk&gt;</p></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install Net::LibAsyncNS, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm Net::LibAsyncNS</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install Net::LibAsyncNS</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./Net::LibAsyncNS.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
